home *** CD-ROM | disk | FTP | other *** search
/ Risc World 7 / Risc World 7.iso / Software / Issue6 / SDL.ZIP / !gcc / docs / gperf < prev    next >
Text File  |  2006-09-17  |  76KB  |  1,695 lines
  1. This is /home/john/gccsdk/riscos/riscos-dist/!gcc/docs/gperf, produced
  2. by makeinfo version 4.8 from doc/gperf.texi.
  3.  
  4. INFO-DIR-SECTION Programming Tools
  5. START-INFO-DIR-ENTRY
  6. * Gperf: (gperf).                Perfect Hash Function Generator.
  7. END-INFO-DIR-ENTRY
  8.  
  9.    This file documents the features of the GNU Perfect Hash Function
  10. Generator 3.0.1.
  11.  
  12.    Copyright (C) 1989-2003 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of this
  15. manual provided the copyright notice and this permission notice are
  16. preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided also
  20. that the section entitled "GNU General Public License" is included
  21. exactly as in the original, and provided that the entire resulting
  22. derived work is distributed under the terms of a permission notice
  23. identical to this one.
  24.  
  25.    Permission is granted to copy and distribute translations of this
  26. manual into another language, under the above conditions for modified
  27. versions, except that the section entitled "GNU General Public License"
  28. and this permission notice may be included in translations approved by
  29. the Free Software Foundation instead of in the original English.
  30.  
  31. 
  32. File: gperf,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
  33.  
  34. Introduction
  35. ************
  36.  
  37. This manual documents the GNU `gperf' perfect hash function generator
  38. utility, focusing on its features and how to use them, and how to report
  39. bugs.
  40.  
  41. * Menu:
  42.  
  43. * Copying::                     GNU `gperf' General Public License says
  44.                                 how you can copy and share `gperf'.
  45. * Contributors::                People who have contributed to `gperf'.
  46. * Motivation::                  The purpose of `gperf'.
  47. * Search Structures::           Static search structures and GNU `gperf'
  48. * Description::                 High-level discussion of how GPERF functions.
  49. * Options::                     A description of options to the program.
  50. * Bugs::                        Known bugs and limitations with GPERF.
  51. * Projects::                    Things still left to do.
  52. * Bibliography::                Material Referenced in this Report.
  53.  
  54. * Concept Index::
  55.  
  56.  
  57. High-Level Description of GNU `gperf'
  58.  
  59. * Input Format::                Input Format to `gperf'
  60. * Output Format::               Output Format for Generated C Code with `gperf'
  61. * Binary Strings::              Use of NUL bytes
  62.  
  63. Input Format to `gperf'
  64.  
  65. * Declarations::                Declarations.
  66. * Keywords::                    Format for Keyword Entries.
  67. * Functions::                   Including Additional C Functions.
  68. * Controls for GNU indent::     Where to place directives for GNU `indent'.
  69.  
  70. Declarations
  71.  
  72. * User-supplied Struct::        Specifying keywords with attributes.
  73. * Gperf Declarations::          Embedding command line options in the input.
  74. * C Code Inclusion::            Including C declarations and definitions.
  75.  
  76. Invoking `gperf'
  77.  
  78. * Input Details::               Options that affect Interpretation of the Input File
  79. * Output Language::             Specifying the Language for the Output Code
  80. * Output Details::              Fine tuning Details in the Output Code
  81. * Algorithmic Details::         Changing the Algorithms employed by `gperf'
  82. * Verbosity::                   Informative Output
  83.  
  84. 
  85. File: gperf,  Node: Copying,  Next: Contributors,  Prev: Top,  Up: Top
  86.  
  87. GNU GENERAL PUBLIC LICENSE
  88. **************************
  89.  
  90.                          Version 2, June 1991
  91.  
  92.      Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
  93.      59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  94.  
  95.      Everyone is permitted to copy and distribute verbatim copies
  96.      of this license document, but changing it is not allowed.
  97.  
  98. Preamble
  99. ========
  100.  
  101. The licenses for most software are designed to take away your freedom
  102. to share and change it.  By contrast, the GNU General Public License is
  103. intended to guarantee your freedom to share and change free
  104. software--to make sure the software is free for all its users.  This
  105. General Public License applies to most of the Free Software
  106. Foundation's software and to any other program whose authors commit to
  107. using it.  (Some other Free Software Foundation software is covered by
  108. the GNU Library General Public License instead.)  You can apply it to
  109. your programs, too.
  110.  
  111.    When we speak of free software, we are referring to freedom, not
  112. price.  Our General Public Licenses are designed to make sure that you
  113. have the freedom to distribute copies of free software (and charge for
  114. this service if you wish), that you receive source code or can get it
  115. if you want it, that you can change the software or use pieces of it in
  116. new free programs; and that you know you can do these things.
  117.  
  118.    To protect your rights, we need to make restrictions that forbid
  119. anyone to deny you these rights or to ask you to surrender the rights.
  120. These restrictions translate to certain responsibilities for you if you
  121. distribute copies of the software, or if you modify it.
  122.  
  123.    For example, if you distribute copies of such a program, whether
  124. gratis or for a fee, you must give the recipients all the rights that
  125. you have.  You must make sure that they, too, receive or can get the
  126. source code.  And you must show them these terms so they know their
  127. rights.
  128.  
  129.    We protect your rights with two steps: (1) copyright the software,
  130. and (2) offer you this license which gives you legal permission to copy,
  131. distribute and/or modify the software.
  132.  
  133.    Also, for each author's protection and ours, we want to make certain
  134. that everyone understands that there is no warranty for this free
  135. software.  If the software is modified by someone else and passed on, we
  136. want its recipients to know that what they have is not the original, so
  137. that any problems introduced by others will not reflect on the original
  138. authors' reputations.
  139.  
  140.    Finally, any free program is threatened constantly by software
  141. patents.  We wish to avoid the danger that redistributors of a free
  142. program will individually obtain patent licenses, in effect making the
  143. program proprietary.  To prevent this, we have made it clear that any
  144. patent must be licensed for everyone's free use or not licensed at all.
  145.  
  146.    The precise terms and conditions for copying, distribution and
  147. modification follow.
  148.  
  149.     TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  150.   0. This License applies to any program or other work which contains a
  151.      notice placed by the copyright holder saying it may be distributed
  152.      under the terms of this General Public License.  The "Program",
  153.      below, refers to any such program or work, and a "work based on
  154.      the Program" means either the Program or any derivative work under
  155.      copyright law: that is to say, a work containing the Program or a
  156.      portion of it, either verbatim or with modifications and/or
  157.      translated into another language.  (Hereinafter, translation is
  158.      included without limitation in the term "modification".)  Each
  159.      licensee is addressed as "you".
  160.  
  161.      Activities other than copying, distribution and modification are
  162.      not covered by this License; they are outside its scope.  The act
  163.      of running the Program is not restricted, and the output from the
  164.      Program is covered only if its contents constitute a work based on
  165.      the Program (independent of having been made by running the
  166.      Program).  Whether that is true depends on what the Program does.
  167.  
  168.   1. You may copy and distribute verbatim copies of the Program's
  169.      source code as you receive it, in any medium, provided that you
  170.      conspicuously and appropriately publish on each copy an appropriate
  171.      copyright notice and disclaimer of warranty; keep intact all the
  172.      notices that refer to this License and to the absence of any
  173.      warranty; and give any other recipients of the Program a copy of
  174.      this License along with the Program.
  175.  
  176.      You may charge a fee for the physical act of transferring a copy,
  177.      and you may at your option offer warranty protection in exchange
  178.      for a fee.
  179.  
  180.   2. You may modify your copy or copies of the Program or any portion
  181.      of it, thus forming a work based on the Program, and copy and
  182.      distribute such modifications or work under the terms of Section 1
  183.      above, provided that you also meet all of these conditions:
  184.  
  185.        a. You must cause the modified files to carry prominent notices
  186.           stating that you changed the files and the date of any change.
  187.  
  188.        b. You must cause any work that you distribute or publish, that
  189.           in whole or in part contains or is derived from the Program
  190.           or any part thereof, to be licensed as a whole at no charge
  191.           to all third parties under the terms of this License.
  192.  
  193.        c. If the modified program normally reads commands interactively
  194.           when run, you must cause it, when started running for such
  195.           interactive use in the most ordinary way, to print or display
  196.           an announcement including an appropriate copyright notice and
  197.           a notice that there is no warranty (or else, saying that you
  198.           provide a warranty) and that users may redistribute the
  199.           program under these conditions, and telling the user how to
  200.           view a copy of this License.  (Exception: if the Program
  201.           itself is interactive but does not normally print such an
  202.           announcement, your work based on the Program is not required
  203.           to print an announcement.)
  204.  
  205.      These requirements apply to the modified work as a whole.  If
  206.      identifiable sections of that work are not derived from the
  207.      Program, and can be reasonably considered independent and separate
  208.      works in themselves, then this License, and its terms, do not
  209.      apply to those sections when you distribute them as separate
  210.      works.  But when you distribute the same sections as part of a
  211.      whole which is a work based on the Program, the distribution of
  212.      the whole must be on the terms of this License, whose permissions
  213.      for other licensees extend to the entire whole, and thus to each
  214.      and every part regardless of who wrote it.
  215.  
  216.      Thus, it is not the intent of this section to claim rights or
  217.      contest your rights to work written entirely by you; rather, the
  218.      intent is to exercise the right to control the distribution of
  219.      derivative or collective works based on the Program.
  220.  
  221.      In addition, mere aggregation of another work not based on the
  222.      Program with the Program (or with a work based on the Program) on
  223.      a volume of a storage or distribution medium does not bring the
  224.      other work under the scope of this License.
  225.  
  226.   3. You may copy and distribute the Program (or a work based on it,
  227.      under Section 2) in object code or executable form under the terms
  228.      of Sections 1 and 2 above provided that you also do one of the
  229.      following:
  230.  
  231.        a. Accompany it with the complete corresponding machine-readable
  232.           source code, which must be distributed under the terms of
  233.           Sections 1 and 2 above on a medium customarily used for
  234.           software interchange; or,
  235.  
  236.        b. Accompany it with a written offer, valid for at least three
  237.           years, to give any third party, for a charge no more than your
  238.           cost of physically performing source distribution, a complete
  239.           machine-readable copy of the corresponding source code, to be
  240.           distributed under the terms of Sections 1 and 2 above on a
  241.           medium customarily used for software interchange; or,
  242.  
  243.        c. Accompany it with the information you received as to the offer
  244.           to distribute corresponding source code.  (This alternative is
  245.           allowed only for noncommercial distribution and only if you
  246.           received the program in object code or executable form with
  247.           such an offer, in accord with Subsection b above.)
  248.  
  249.      The source code for a work means the preferred form of the work for
  250.      making modifications to it.  For an executable work, complete
  251.      source code means all the source code for all modules it contains,
  252.      plus any associated interface definition files, plus the scripts
  253.      used to control compilation and installation of the executable.
  254.      However, as a special exception, the source code distributed need
  255.      not include anything that is normally distributed (in either
  256.      source or binary form) with the major components (compiler,
  257.      kernel, and so on) of the operating system on which the executable
  258.      runs, unless that component itself accompanies the executable.
  259.  
  260.      If distribution of executable or object code is made by offering
  261.      access to copy from a designated place, then offering equivalent
  262.      access to copy the source code from the same place counts as
  263.      distribution of the source code, even though third parties are not
  264.      compelled to copy the source along with the object code.
  265.  
  266.   4. You may not copy, modify, sublicense, or distribute the Program
  267.      except as expressly provided under this License.  Any attempt
  268.      otherwise to copy, modify, sublicense or distribute the Program is
  269.      void, and will automatically terminate your rights under this
  270.      License.  However, parties who have received copies, or rights,
  271.      from you under this License will not have their licenses
  272.      terminated so long as such parties remain in full compliance.
  273.  
  274.   5. You are not required to accept this License, since you have not
  275.      signed it.  However, nothing else grants you permission to modify
  276.      or distribute the Program or its derivative works.  These actions
  277.      are prohibited by law if you do not accept this License.
  278.      Therefore, by modifying or distributing the Program (or any work
  279.      based on the Program), you indicate your acceptance of this
  280.      License to do so, and all its terms and conditions for copying,
  281.      distributing or modifying the Program or works based on it.
  282.  
  283.   6. Each time you redistribute the Program (or any work based on the
  284.      Program), the recipient automatically receives a license from the
  285.      original licensor to copy, distribute or modify the Program
  286.      subject to these terms and conditions.  You may not impose any
  287.      further restrictions on the recipients' exercise of the rights
  288.      granted herein.  You are not responsible for enforcing compliance
  289.      by third parties to this License.
  290.  
  291.   7. If, as a consequence of a court judgment or allegation of patent
  292.      infringement or for any other reason (not limited to patent
  293.      issues), conditions are imposed on you (whether by court order,
  294.      agreement or otherwise) that contradict the conditions of this
  295.      License, they do not excuse you from the conditions of this
  296.      License.  If you cannot distribute so as to satisfy simultaneously
  297.      your obligations under this License and any other pertinent
  298.      obligations, then as a consequence you may not distribute the
  299.      Program at all.  For example, if a patent license would not permit
  300.      royalty-free redistribution of the Program by all those who
  301.      receive copies directly or indirectly through you, then the only
  302.      way you could satisfy both it and this License would be to refrain
  303.      entirely from distribution of the Program.
  304.  
  305.      If any portion of this section is held invalid or unenforceable
  306.      under any particular circumstance, the balance of the section is
  307.      intended to apply and the section as a whole is intended to apply
  308.      in other circumstances.
  309.  
  310.      It is not the purpose of this section to induce you to infringe any
  311.      patents or other property right claims or to contest validity of
  312.      any such claims; this section has the sole purpose of protecting
  313.      the integrity of the free software distribution system, which is
  314.      implemented by public license practices.  Many people have made
  315.      generous contributions to the wide range of software distributed
  316.      through that system in reliance on consistent application of that
  317.      system; it is up to the author/donor to decide if he or she is
  318.      willing to distribute software through any other system and a
  319.      licensee cannot impose that choice.
  320.  
  321.      This section is intended to make thoroughly clear what is believed
  322.      to be a consequence of the rest of this License.
  323.  
  324.   8. If the distribution and/or use of the Program is restricted in
  325.      certain countries either by patents or by copyrighted interfaces,
  326.      the original copyright holder who places the Program under this
  327.      License may add an explicit geographical distribution limitation
  328.      excluding those countries, so that distribution is permitted only
  329.      in or among countries not thus excluded.  In such case, this
  330.      License incorporates the limitation as if written in the body of
  331.      this License.
  332.  
  333.   9. The Free Software Foundation may publish revised and/or new
  334.      versions of the General Public License from time to time.  Such
  335.      new versions will be similar in spirit to the present version, but
  336.      may differ in detail to address new problems or concerns.
  337.  
  338.      Each version is given a distinguishing version number.  If the
  339.      Program specifies a version number of this License which applies
  340.      to it and "any later version", you have the option of following
  341.      the terms and conditions either of that version or of any later
  342.      version published by the Free Software Foundation.  If the Program
  343.      does not specify a version number of this License, you may choose
  344.      any version ever published by the Free Software Foundation.
  345.  
  346.  10. If you wish to incorporate parts of the Program into other free
  347.      programs whose distribution conditions are different, write to the
  348.      author to ask for permission.  For software which is copyrighted
  349.      by the Free Software Foundation, write to the Free Software
  350.      Foundation; we sometimes make exceptions for this.  Our decision
  351.      will be guided by the two goals of preserving the free status of
  352.      all derivatives of our free software and of promoting the sharing
  353.      and reuse of software generally.
  354.  
  355.                                 NO WARRANTY
  356.  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
  357.      WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
  358.      LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
  359.      HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
  360.      WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
  361.      NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  362.      FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
  363.      QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
  364.      PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  365.      SERVICING, REPAIR OR CORRECTION.
  366.  
  367.  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
  368.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
  369.      MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
  370.      LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
  371.      INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  372.      INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
  373.      DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
  374.      OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
  375.      OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
  376.      ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  377.  
  378.                       END OF TERMS AND CONDITIONS
  379. How to Apply These Terms to Your New Programs
  380. =============================================
  381.  
  382. If you develop a new program, and you want it to be of the greatest
  383. possible use to the public, the best way to achieve this is to make it
  384. free software which everyone can redistribute and change under these
  385. terms.
  386.  
  387.    To do so, attach the following notices to the program.  It is safest
  388. to attach them to the start of each source file to most effectively
  389. convey the exclusion of warranty; and each file should have at least
  390. the "copyright" line and a pointer to where the full notice is found.
  391.  
  392.      ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
  393.      Copyright (C) YEAR  NAME OF AUTHOR
  394.  
  395.      This program is free software; you can redistribute it and/or
  396.      modify it under the terms of the GNU General Public License
  397.      as published by the Free Software Foundation; either version 2
  398.      of the License, or (at your option) any later version.
  399.  
  400.      This program is distributed in the hope that it will be useful,
  401.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  402.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  403.      GNU General Public License for more details.
  404.  
  405.      You should have received a copy of the GNU General Public License
  406.      along with this program; if not, write to the Free Software
  407.      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  408.  
  409.    Also add information on how to contact you by electronic and paper
  410. mail.
  411.  
  412.    If the program is interactive, make it output a short notice like
  413. this when it starts in an interactive mode:
  414.  
  415.      Gnomovision version 69, Copyright (C) YEAR  NAME OF AUTHOR
  416.      Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
  417.      type `show w'.  This is free software, and you are welcome
  418.      to redistribute it under certain conditions; type `show c'
  419.      for details.
  420.  
  421.    The hypothetical commands `show w' and `show c' should show the
  422. appropriate parts of the General Public License.  Of course, the
  423. commands you use may be called something other than `show w' and `show
  424. c'; they could even be mouse-clicks or menu items--whatever suits your
  425. program.
  426.  
  427.    You should also get your employer (if you work as a programmer) or
  428. your school, if any, to sign a "copyright disclaimer" for the program,
  429. if necessary.  Here is a sample; alter the names:
  430.  
  431.      Yoyodyne, Inc., hereby disclaims all copyright
  432.      interest in the program `Gnomovision'
  433.      (which makes passes at compilers) written
  434.      by James Hacker.
  435.  
  436.      SIGNATURE OF TY COON, 1 April 1989
  437.      Ty Coon, President of Vice
  438.  
  439.    This General Public License does not permit incorporating your
  440. program into proprietary programs.  If your program is a subroutine
  441. library, you may consider it more useful to permit linking proprietary
  442. applications with the library.  If this is what you want to do, use the
  443. GNU Library General Public License instead of this License.
  444.  
  445. 
  446. File: gperf,  Node: Contributors,  Next: Motivation,  Prev: Copying,  Up: Top
  447.  
  448. Contributors to GNU `gperf' Utility
  449. ***********************************
  450.  
  451.    * The GNU `gperf' perfect hash function generator utility was
  452.      written in GNU C++ by Douglas C. Schmidt.  The general idea for
  453.      the perfect hash function generator was inspired by Keith Bostic's
  454.      algorithm written in C, and distributed to net.sources around
  455.      1984.  The current program is a heavily modified, enhanced, and
  456.      extended implementation of Keith's basic idea, created at the
  457.      University of California, Irvine.  Bugs, patches, and suggestions
  458.      should be reported to `<bug-gnu-gperf@gnu.org>'.
  459.  
  460.    * Special thanks is extended to Michael Tiemann and Doug Lea, for
  461.      providing a useful compiler, and for giving me a forum to exhibit
  462.      my creation.
  463.  
  464.      In addition, Adam de Boor and Nels Olson provided many tips and
  465.      insights that greatly helped improve the quality and functionality
  466.      of `gperf'.
  467.  
  468.    * Bruno Haible enhanced and optimized the search algorithm.  He also
  469.      rewrote the input routines and the output routines for better
  470.      reliability, and added a testsuite.
  471.  
  472. 
  473. File: gperf,  Node: Motivation,  Next: Search Structures,  Prev: Contributors,  Up: Top
  474.  
  475. 1 Introduction
  476. **************
  477.  
  478. `gperf' is a perfect hash function generator written in C++.  It
  479. transforms an N element user-specified keyword set W into a perfect
  480. hash function F.  F uniquely maps keywords in W onto the range 0..K,
  481. where K >= N-1.  If K = N-1 then F is a _minimal_ perfect hash function.
  482. `gperf' generates a 0..K element static lookup table and a pair of C
  483. functions.  These functions determine whether a given character string
  484. S occurs in W, using at most one probe into the lookup table.
  485.  
  486.    `gperf' currently generates the reserved keyword recognizer for
  487. lexical analyzers in several production and research compilers and
  488. language processing tools, including GNU C, GNU C++, GNU Java, GNU
  489. Pascal, GNU Modula 3, and GNU indent.  Complete C++ source code for
  490. `gperf' is available from `http://ftp.gnu.org/pub/gnu/gperf/'.  A paper
  491. describing `gperf''s design and implementation in greater detail is
  492. available in the Second USENIX C++ Conference proceedings or from
  493. `http://www.cs.wustl.edu/~schmidt/resume.html'.
  494.  
  495. 
  496. File: gperf,  Node: Search Structures,  Next: Description,  Prev: Motivation,  Up: Top
  497.  
  498. 2 Static search structures and GNU `gperf'
  499. ******************************************
  500.  
  501. A "static search structure" is an Abstract Data Type with certain
  502. fundamental operations, e.g., _initialize_, _insert_, and _retrieve_.
  503. Conceptually, all insertions occur before any retrievals.  In practice,
  504. `gperf' generates a _static_ array containing search set keywords and
  505. any associated attributes specified by the user.  Thus, there is
  506. essentially no execution-time cost for the insertions.  It is a useful
  507. data structure for representing _static search sets_.  Static search
  508. sets occur frequently in software system applications.  Typical static
  509. search sets include compiler reserved words, assembler instruction
  510. opcodes, and built-in shell interpreter commands.  Search set members,
  511. called "keywords", are inserted into the structure only once, usually
  512. during program initialization, and are not generally modified at
  513. run-time.
  514.  
  515.    Numerous static search structure implementations exist, e.g.,
  516. arrays, linked lists, binary search trees, digital search tries, and
  517. hash tables.  Different approaches offer trade-offs between space
  518. utilization and search time efficiency.  For example, an N element
  519. sorted array is space efficient, though the average-case time
  520. complexity for retrieval operations using binary search is proportional
  521. to log N.  Conversely, hash table implementations often locate a table
  522. entry in constant time, but typically impose additional memory overhead
  523. and exhibit poor worst case performance.
  524.  
  525.    _Minimal perfect hash functions_ provide an optimal solution for a
  526. particular class of static search sets.  A minimal perfect hash
  527. function is defined by two properties:
  528.  
  529.    * It allows keyword recognition in a static search set using at most
  530.      _one_ probe into the hash table.  This represents the "perfect"
  531.      property.
  532.  
  533.    * The actual memory allocated to store the keywords is precisely
  534.      large enough for the keyword set, and _no larger_.  This is the
  535.      "minimal" property.
  536.  
  537.    For most applications it is far easier to generate _perfect_ hash
  538. functions than _minimal perfect_ hash functions.  Moreover, non-minimal
  539. perfect hash functions frequently execute faster than minimal ones in
  540. practice.  This phenomena occurs since searching a sparse keyword table
  541. increases the probability of locating a "null" entry, thereby reducing
  542. string comparisons.  `gperf''s default behavior generates
  543. _near-minimal_ perfect hash functions for keyword sets.  However,
  544. `gperf' provides many options that permit user control over the degree
  545. of minimality and perfection.
  546.  
  547.    Static search sets often exhibit relative stability over time.  For
  548. example, Ada's 63 reserved words have remained constant for nearly a
  549. decade.  It is therefore frequently worthwhile to expend concerted
  550. effort building an optimal search structure _once_, if it subsequently
  551. receives heavy use multiple times.  `gperf' removes the drudgery
  552. associated with constructing time- and space-efficient search
  553. structures by hand.  It has proven a useful and practical tool for
  554. serious programming projects.  Output from `gperf' is currently used in
  555. several production and research compilers, including GNU C, GNU C++,
  556. GNU Java, GNU Pascal, and GNU Modula 3.  The latter two compilers are
  557. not yet part of the official GNU distribution.  Each compiler utilizes
  558. `gperf' to automatically generate static search structures that
  559. efficiently identify their respective reserved keywords.
  560.  
  561. 
  562. File: gperf,  Node: Description,  Next: Options,  Prev: Search Structures,  Up: Top
  563.  
  564. 3 High-Level Description of GNU `gperf'
  565. ***************************************
  566.  
  567. * Menu:
  568.  
  569. * Input Format::                Input Format to `gperf'
  570. * Output Format::               Output Format for Generated C Code with `gperf'
  571. * Binary Strings::              Use of NUL bytes
  572.  
  573.    The perfect hash function generator `gperf' reads a set of
  574. "keywords" from an input file (or from the standard input by default).
  575. It attempts to derive a perfect hashing function that recognizes a
  576. member of the "static keyword set" with at most a single probe into the
  577. lookup table.  If `gperf' succeeds in generating such a function it
  578. produces a pair of C source code routines that perform hashing and
  579. table lookup recognition.  All generated C code is directed to the
  580. standard output.  Command-line options described below allow you to
  581. modify the input and output format to `gperf'.
  582.  
  583.    By default, `gperf' attempts to produce time-efficient code, with
  584. less emphasis on efficient space utilization.  However, several options
  585. exist that permit trading-off execution time for storage space and vice
  586. versa.  In particular, expanding the generated table size produces a
  587. sparse search structure, generally yielding faster searches.
  588. Conversely, you can direct `gperf' to utilize a C `switch' statement
  589. scheme that minimizes data space storage size.  Furthermore, using a C
  590. `switch' may actually speed up the keyword retrieval time somewhat.
  591. Actual results depend on your C compiler, of course.
  592.  
  593.    In general, `gperf' assigns values to the bytes it is using for
  594. hashing until some set of values gives each keyword a unique value.  A
  595. helpful heuristic is that the larger the hash value range, the easier
  596. it is for `gperf' to find and generate a perfect hash function.
  597. Experimentation is the key to getting the most from `gperf'.
  598.  
  599. 
  600. File: gperf,  Node: Input Format,  Next: Output Format,  Prev: Description,  Up: Description
  601.  
  602. 3.1 Input Format to `gperf'
  603. ===========================
  604.  
  605. You can control the input file format by varying certain command-line
  606. arguments, in particular the `-t' option.  The input's appearance is
  607. similar to GNU utilities `flex' and `bison' (or UNIX utilities `lex'
  608. and `yacc').  Here's an outline of the general format:
  609.  
  610.      declarations
  611.      %%
  612.      keywords
  613.      %%
  614.      functions
  615.  
  616.    _Unlike_ `flex' or `bison', the declarations section and the
  617. functions section are optional.  The following sections describe the
  618. input format for each section.
  619.  
  620. * Menu:
  621.  
  622. * Declarations::                Declarations.
  623. * Keywords::                    Format for Keyword Entries.
  624. * Functions::                   Including Additional C Functions.
  625. * Controls for GNU indent::     Where to place directives for GNU `indent'.
  626.  
  627.    It is possible to omit the declaration section entirely, if the `-t'
  628. option is not given.  In this case the input file begins directly with
  629. the first keyword line, e.g.:
  630.  
  631.      january
  632.      february
  633.      march
  634.      april
  635.      ...
  636.  
  637. 
  638. File: gperf,  Node: Declarations,  Next: Keywords,  Prev: Input Format,  Up: Input Format
  639.  
  640. 3.1.1 Declarations
  641. ------------------
  642.  
  643. The keyword input file optionally contains a section for including
  644. arbitrary C declarations and definitions, `gperf' declarations that act
  645. like command-line options, as well as for providing a user-supplied
  646. `struct'.
  647.  
  648. * Menu:
  649.  
  650. * User-supplied Struct::        Specifying keywords with attributes.
  651. * Gperf Declarations::          Embedding command line options in the input.
  652. * C Code Inclusion::            Including C declarations and definitions.
  653.  
  654. 
  655. File: gperf,  Node: User-supplied Struct,  Next: Gperf Declarations,  Prev: Declarations,  Up: Declarations
  656.  
  657. 3.1.1.1 User-supplied `struct'
  658. ..............................
  659.  
  660. If the `-t' option (or, equivalently, the `%struct-type' declaration)
  661. _is_ enabled, you _must_ provide a C `struct' as the last component in
  662. the declaration section from the input file.  The first field in this
  663. struct must be of type `char *' or `const char *' if the `-P' option is
  664. not given, or of type `int' if the option `-P' (or, equivalently, the
  665. `%pic' declaration) is enabled.  This first field must be called
  666. `name', although it is possible to modify its name with the `-K' option
  667. (or, equivalently, the `%define slot-name' declaration) described below.
  668.  
  669.    Here is a simple example, using months of the year and their
  670. attributes as input:
  671.  
  672.      struct month { char *name; int number; int days; int leap_days; };
  673.      %%
  674.      january,   1, 31, 31
  675.      february,  2, 28, 29
  676.      march,     3, 31, 31
  677.      april,     4, 30, 30
  678.      may,       5, 31, 31
  679.      june,      6, 30, 30
  680.      july,      7, 31, 31
  681.      august,    8, 31, 31
  682.      september, 9, 30, 30
  683.      october,  10, 31, 31
  684.      november, 11, 30, 30
  685.      december, 12, 31, 31
  686.  
  687.    Separating the `struct' declaration from the list of keywords and
  688. other fields are a pair of consecutive percent signs, `%%', appearing
  689. left justified in the first column, as in the UNIX utility `lex'.
  690.  
  691.    If the `struct' has already been declared in an include file, it can
  692. be mentioned in an abbreviated form, like this:
  693.  
  694.      struct month;
  695.      %%
  696.      january,   1, 31, 31
  697.      ...
  698.  
  699. 
  700. File: gperf,  Node: Gperf Declarations,  Next: C Code Inclusion,  Prev: User-supplied Struct,  Up: Declarations
  701.  
  702. 3.1.1.2 Gperf Declarations
  703. ..........................
  704.  
  705. The declaration section can contain `gperf' declarations.  They
  706. influence the way `gperf' works, like command line options do.  In
  707. fact, every such declaration is equivalent to a command line option.
  708. There are three forms of declarations:
  709.  
  710.   1. Declarations without argument, like `%compare-lengths'.
  711.  
  712.   2. Declarations with an argument, like `%switch=COUNT'.
  713.  
  714.   3. Declarations of names of entities in the output file, like
  715.      `%define lookup-function-name NAME'.
  716.  
  717.    When a declaration is given both in the input file and as a command
  718. line option, the command-line option's value prevails.
  719.  
  720.    The following `gperf' declarations are available.
  721.  
  722. `%delimiters=DELIMITER-LIST'
  723.      Allows you to provide a string containing delimiters used to
  724.      separate keywords from their attributes.  The default is ",".  This
  725.      option is essential if you want to use keywords that have embedded
  726.      commas or newlines.
  727.  
  728. `%struct-type'
  729.      Allows you to include a `struct' type declaration for generated
  730.      code; see above for an example.
  731.  
  732. `%ignore-case'
  733.      Consider upper and lower case ASCII characters as equivalent.  The
  734.      string comparison will use a case insignificant character
  735.      comparison.  Note that locale dependent case mappings are ignored.
  736.  
  737. `%language=LANGUAGE-NAME'
  738.      Instructs `gperf' to generate code in the language specified by the
  739.      option's argument.  Languages handled are currently:
  740.  
  741.     `KR-C'
  742.           Old-style K&R C.  This language is understood by old-style C
  743.           compilers and ANSI C compilers, but ANSI C compilers may flag
  744.           warnings (or even errors) because of lacking `const'.
  745.  
  746.     `C'
  747.           Common C.  This language is understood by ANSI C compilers,
  748.           and also by old-style C compilers, provided that you `#define
  749.           const' to empty for compilers which don't know about this
  750.           keyword.
  751.  
  752.     `ANSI-C'
  753.           ANSI C.  This language is understood by ANSI C compilers and
  754.           C++ compilers.
  755.  
  756.     `C++'
  757.           C++.  This language is understood by C++ compilers.
  758.  
  759.      The default is C.
  760.  
  761. `%define slot-name NAME'
  762.      This declaration is only useful when option `-t' (or,
  763.      equivalently, the `%struct-type' declaration) has been given.  By
  764.      default, the program assumes the structure component identifier for
  765.      the keyword is `name'.  This option allows an arbitrary choice of
  766.      identifier for this component, although it still must occur as the
  767.      first field in your supplied `struct'.
  768.  
  769. `%define initializer-suffix INITIALIZERS'
  770.      This declaration is only useful when option `-t' (or,
  771.      equivalently, the `%struct-type' declaration) has been given.  It
  772.      permits to specify initializers for the structure members following
  773.      SLOT-NAME in empty hash table entries.  The list of initializers
  774.      should start with a comma.  By default, the emitted code will
  775.      zero-initialize structure members following SLOT-NAME.
  776.  
  777. `%define hash-function-name NAME'
  778.      Allows you to specify the name for the generated hash function.
  779.      Default name is `hash'.  This option permits the use of two hash
  780.      tables in the same file.
  781.  
  782. `%define lookup-function-name NAME'
  783.      Allows you to specify the name for the generated lookup function.
  784.      Default name is `in_word_set'.  This option permits multiple
  785.      generated hash functions to be used in the same application.
  786.  
  787. `%define class-name NAME'
  788.      This option is only useful when option `-L C++' (or, equivalently,
  789.      the `%language=C++' declaration) has been given.  It allows you to
  790.      specify the name of generated C++ class.  Default name is
  791.      `Perfect_Hash'.
  792.  
  793. `%7bit'
  794.      This option specifies that all strings that will be passed as
  795.      arguments to the generated hash function and the generated lookup
  796.      function will solely consist of 7-bit ASCII characters (bytes in
  797.      the range 0..127).  (Note that the ANSI C functions `isalnum' and
  798.      `isgraph' do _not_ guarantee that a byte is in this range.  Only
  799.      an explicit test like `c >= 'A' && c <= 'Z'' guarantees this.)
  800.  
  801. `%compare-lengths'
  802.      Compare keyword lengths before trying a string comparison.  This
  803.      option is mandatory for binary comparisons (*note Binary
  804.      Strings::).  It also might cut down on the number of string
  805.      comparisons made during the lookup, since keywords with different
  806.      lengths are never compared via `strcmp'.  However, using
  807.      `%compare-lengths' might greatly increase the size of the
  808.      generated C code if the lookup table range is large (which implies
  809.      that the switch option `-S' or `%switch' is not enabled), since
  810.      the length table contains as many elements as there are entries in
  811.      the lookup table.
  812.  
  813. `%compare-strncmp'
  814.      Generates C code that uses the `strncmp' function to perform
  815.      string comparisons.  The default action is to use `strcmp'.
  816.  
  817. `%readonly-tables'
  818.      Makes the contents of all generated lookup tables constant, i.e.,
  819.      "readonly".  Many compilers can generate more efficient code for
  820.      this by putting the tables in readonly memory.
  821.  
  822. `%enum'
  823.      Define constant values using an enum local to the lookup function
  824.      rather than with #defines.  This also means that different lookup
  825.      functions can reside in the same file.  Thanks to James Clark
  826.      `<jjc@ai.mit.edu>'.
  827.  
  828. `%includes'
  829.      Include the necessary system include file, `<string.h>', at the
  830.      beginning of the code.  By default, this is not done; the user must
  831.      include this header file himself to allow compilation of the code.
  832.  
  833. `%global-table'
  834.      Generate the static table of keywords as a static global variable,
  835.      rather than hiding it inside of the lookup function (which is the
  836.      default behavior).
  837.  
  838. `%pic'
  839.      Optimize the generated table for inclusion in shared libraries.
  840.      This reduces the startup time of programs using a shared library
  841.      containing the generated code.  If the `%struct-type' declaration
  842.      (or, equivalently, the option `-t') is also given, the first field
  843.      of the user-defined struct must be of type `int', not `char *',
  844.      because it will contain offsets into the string pool instead of
  845.      actual strings.  To convert such an offset to a string, you can
  846.      use the expression `stringpool + O', where O is the offset.  The
  847.      string pool name can be changed through the `%define
  848.      string-pool-name' declaration.
  849.  
  850. `%define string-pool-name NAME'
  851.      Allows you to specify the name of the generated string pool
  852.      created by the declaration `%pic' (or, equivalently, the option
  853.      `-P').  The default name is `stringpool'.  This declaration
  854.      permits the use of two hash tables in the same file, with `%pic'
  855.      and even when the `%global-table' declaration (or, equivalently,
  856.      the option `-G') is given.
  857.  
  858. `%null-strings'
  859.      Use NULL strings instead of empty strings for empty keyword table
  860.      entries.  This reduces the startup time of programs using a shared
  861.      library containing the generated code (but not as much as the
  862.      declaration `%pic'), at the expense of one more test-and-branch
  863.      instruction at run time.
  864.  
  865. `%define word-array-name NAME'
  866.      Allows you to specify the name for the generated array containing
  867.      the hash table.  Default name is `wordlist'.  This option permits
  868.      the use of two hash tables in the same file, even when the option
  869.      `-G' (or, equivalently, the `%global-table' declaration) is given.
  870.  
  871. `%switch=COUNT'
  872.      Causes the generated C code to use a `switch' statement scheme,
  873.      rather than an array lookup table.  This can lead to a reduction
  874.      in both time and space requirements for some input files.  The
  875.      argument to this option determines how many `switch' statements
  876.      are generated.  A value of 1 generates 1 `switch' containing all
  877.      the elements, a value of 2 generates 2 tables with 1/2 the
  878.      elements in each `switch', etc.  This is useful since many C
  879.      compilers cannot correctly generate code for large `switch'
  880.      statements.  This option was inspired in part by Keith Bostic's
  881.      original C program.
  882.  
  883. `%omit-struct-type'
  884.      Prevents the transfer of the type declaration to the output file.
  885.      Use this option if the type is already defined elsewhere.
  886.  
  887. 
  888. File: gperf,  Node: C Code Inclusion,  Prev: Gperf Declarations,  Up: Declarations
  889.  
  890. 3.1.1.3 C Code Inclusion
  891. ........................
  892.  
  893. Using a syntax similar to GNU utilities `flex' and `bison', it is
  894. possible to directly include C source text and comments verbatim into
  895. the generated output file.  This is accomplished by enclosing the region
  896. inside left-justified surrounding `%{', `%}' pairs.  Here is an input
  897. fragment based on the previous example that illustrates this feature:
  898.  
  899.      %{
  900.      #include <assert.h>
  901.      /* This section of code is inserted directly into the output. */
  902.      int return_month_days (struct month *months, int is_leap_year);
  903.      %}
  904.      struct month { char *name; int number; int days; int leap_days; };
  905.      %%
  906.      january,   1, 31, 31
  907.      february,  2, 28, 29
  908.      march,     3, 31, 31
  909.      ...
  910.  
  911. 
  912. File: gperf,  Node: Keywords,  Next: Functions,  Prev: Declarations,  Up: Input Format
  913.  
  914. 3.1.2 Format for Keyword Entries
  915. --------------------------------
  916.  
  917. The second input file format section contains lines of keywords and any
  918. associated attributes you might supply.  A line beginning with `#' in
  919. the first column is considered a comment.  Everything following the `#'
  920. is ignored, up to and including the following newline.  A line
  921. beginning with `%' in the first column is an option declaration and
  922. must not occur within the keywords section.
  923.  
  924.    The first field of each non-comment line is always the keyword
  925. itself.  It can be given in two ways: as a simple name, i.e., without
  926. surrounding string quotation marks, or as a string enclosed in
  927. double-quotes, in C syntax, possibly with backslash escapes like `\"'
  928. or `\234' or `\xa8'.  In either case, it must start right at the
  929. beginning of the line, without leading whitespace.  In this context, a
  930. "field" is considered to extend up to, but not include, the first
  931. blank, comma, or newline.  Here is a simple example taken from a
  932. partial list of C reserved words:
  933.  
  934.      # These are a few C reserved words, see the c.gperf file
  935.      # for a complete list of ANSI C reserved words.
  936.      unsigned
  937.      sizeof
  938.      switch
  939.      signed
  940.      if
  941.      default
  942.      for
  943.      while
  944.      return
  945.  
  946.    Note that unlike `flex' or `bison' the first `%%' marker may be
  947. elided if the declaration section is empty.
  948.  
  949.    Additional fields may optionally follow the leading keyword.  Fields
  950. should be separated by commas, and terminate at the end of line.  What
  951. these fields mean is entirely up to you; they are used to initialize the
  952. elements of the user-defined `struct' provided by you in the
  953. declaration section.  If the `-t' option (or, equivalently, the
  954. `%struct-type' declaration) is _not_ enabled these fields are simply
  955. ignored.  All previous examples except the last one contain keyword
  956. attributes.
  957.  
  958. 
  959. File: gperf,  Node: Functions,  Next: Controls for GNU indent,  Prev: Keywords,  Up: Input Format
  960.  
  961. 3.1.3 Including Additional C Functions
  962. --------------------------------------
  963.  
  964. The optional third section also corresponds closely with conventions
  965. found in `flex' and `bison'.  All text in this section, starting at the
  966. final `%%' and extending to the end of the input file, is included
  967. verbatim into the generated output file.  Naturally, it is your
  968. responsibility to ensure that the code contained in this section is
  969. valid C.
  970.  
  971. 
  972. File: gperf,  Node: Controls for GNU indent,  Prev: Functions,  Up: Input Format
  973.  
  974. 3.1.4 Where to place directives for GNU `indent'.
  975. -------------------------------------------------
  976.  
  977. If you want to invoke GNU `indent' on a `gperf' input file, you will
  978. see that GNU `indent' doesn't understand the `%%', `%{' and `%}'
  979. directives that control `gperf''s interpretation of the input file.
  980. Therefore you have to insert some directives for GNU `indent'.  More
  981. precisely, assuming the most general input file structure
  982.  
  983.      declarations part 1
  984.      %{
  985.      verbatim code
  986.      %}
  987.      declarations part 2
  988.      %%
  989.      keywords
  990.      %%
  991.      functions
  992.  
  993. you would insert `*INDENT-OFF*' and `*INDENT-ON*' comments as follows:
  994.  
  995.      /* *INDENT-OFF* */
  996.      declarations part 1
  997.      %{
  998.      /* *INDENT-ON* */
  999.      verbatim code
  1000.      /* *INDENT-OFF* */
  1001.      %}
  1002.      declarations part 2
  1003.      %%
  1004.      keywords
  1005.      %%
  1006.      /* *INDENT-ON* */
  1007.      functions
  1008.  
  1009. 
  1010. File: gperf,  Node: Output Format,  Next: Binary Strings,  Prev: Input Format,  Up: Description
  1011.  
  1012. 3.2 Output Format for Generated C Code with `gperf'
  1013. ===================================================
  1014.  
  1015. Several options control how the generated C code appears on the standard
  1016. output.  Two C function are generated.  They are called `hash' and
  1017. `in_word_set', although you may modify their names with a command-line
  1018. option.  Both functions require two arguments, a string, `char *' STR,
  1019. and a length parameter, `int' LEN.  Their default function prototypes
  1020. are as follows:
  1021.  
  1022.  -- Function: unsigned int hash (const char * STR, unsigned int LEN)
  1023.      By default, the generated `hash' function returns an integer value
  1024.      created by adding LEN to several user-specified STR byte positions
  1025.      indexed into an "associated values" table stored in a local static
  1026.      array.  The associated values table is constructed internally by
  1027.      `gperf' and later output as a static local C array called
  1028.      `hash_table'.  The relevant selected positions (i.e. indices into
  1029.      STR) are specified via the `-k' option when running `gperf', as
  1030.      detailed in the _Options_ section below (*note Options::).
  1031.  
  1032.  -- Function:  in_word_set (const char * STR, unsigned int LEN)
  1033.      If STR is in the keyword set, returns a pointer to that keyword.
  1034.      More exactly, if the option `-t' (or, equivalently, the
  1035.      `%struct-type' declaration) was given, it returns a pointer to the
  1036.      matching keyword's structure.  Otherwise it returns `NULL'.
  1037.  
  1038.    If the option `-c' (or, equivalently, the `%compare-strncmp'
  1039. declaration) is not used, STR must be a NUL terminated string of
  1040. exactly length LEN.  If `-c' (or, equivalently, the `%compare-strncmp'
  1041. declaration) is used, STR must simply be an array of LEN bytes and does
  1042. not need to be NUL terminated.
  1043.  
  1044.    The code generated for these two functions is affected by the
  1045. following options:
  1046.  
  1047. `-t'
  1048. `--struct-type'
  1049.      Make use of the user-defined `struct'.
  1050.  
  1051. `-S TOTAL-SWITCH-STATEMENTS'
  1052. `--switch=TOTAL-SWITCH-STATEMENTS'
  1053.      Generate 1 or more C `switch' statement rather than use a large,
  1054.      (and potentially sparse) static array.  Although the exact time and
  1055.      space savings of this approach vary according to your C compiler's
  1056.      degree of optimization, this method often results in smaller and
  1057.      faster code.
  1058.  
  1059.    If the `-t' and `-S' options (or, equivalently, the `%struct-type'
  1060. and `%switch' declarations) are omitted, the default action is to
  1061. generate a `char *' array containing the keywords, together with
  1062. additional empty strings used for padding the array.  By experimenting
  1063. with the various input and output options, and timing the resulting C
  1064. code, you can determine the best option choices for different keyword
  1065. set characteristics.
  1066.  
  1067. 
  1068. File: gperf,  Node: Binary Strings,  Prev: Output Format,  Up: Description
  1069.  
  1070. 3.3 Use of NUL bytes
  1071. ====================
  1072.  
  1073. By default, the code generated by `gperf' operates on zero terminated
  1074. strings, the usual representation of strings in C.  This means that the
  1075. keywords in the input file must not contain NUL bytes, and the STR
  1076. argument passed to `hash' or `in_word_set' must be NUL terminated and
  1077. have exactly length LEN.
  1078.  
  1079.    If option `-c' (or, equivalently, the `%compare-strncmp'
  1080. declaration) is used, then the STR argument does not need to be NUL
  1081. terminated.  The code generated by `gperf' will only access the first
  1082. LEN, not LEN+1, bytes starting at STR.  However, the keywords in the
  1083. input file still must not contain NUL bytes.
  1084.  
  1085.    If option `-l' (or, equivalently, the `%compare-lengths'
  1086. declaration) is used, then the hash table performs binary comparison.
  1087. The keywords in the input file may contain NUL bytes, written in string
  1088. syntax as `\000' or `\x00', and the code generated by `gperf' will
  1089. treat NUL like any other byte.  Also, in this case the `-c' option (or,
  1090. equivalently, the `%compare-strncmp' declaration) is ignored.
  1091.  
  1092. 
  1093. File: gperf,  Node: Options,  Next: Bugs,  Prev: Description,  Up: Top
  1094.  
  1095. 4 Invoking `gperf'
  1096. ******************
  1097.  
  1098. There are _many_ options to `gperf'.  They were added to make the
  1099. program more convenient for use with real applications.  "On-line" help
  1100. is readily available via the `--help' option.  Here is the complete
  1101. list of options.
  1102.  
  1103. * Menu:
  1104.  
  1105. * Output File::                 Specifying the Location of the Output File
  1106. * Input Details::               Options that affect Interpretation of the Input File
  1107. * Output Language::             Specifying the Language for the Output Code
  1108. * Output Details::              Fine tuning Details in the Output Code
  1109. * Algorithmic Details::         Changing the Algorithms employed by `gperf'
  1110. * Verbosity::                   Informative Output
  1111.  
  1112. 
  1113. File: gperf,  Node: Output File,  Next: Input Details,  Prev: Options,  Up: Options
  1114.  
  1115. 4.1 Specifying the Location of the Output File
  1116. ==============================================
  1117.  
  1118. `--output-file=FILE'
  1119.      Allows you to specify the name of the file to which the output is
  1120.      written to.
  1121.  
  1122.    The results are written to standard output if no output file is
  1123. specified or if it is `-'.
  1124.  
  1125. 
  1126. File: gperf,  Node: Input Details,  Next: Output Language,  Prev: Output File,  Up: Options
  1127.  
  1128. 4.2 Options that affect Interpretation of the Input File
  1129. ========================================================
  1130.  
  1131. These options are also available as declarations in the input file
  1132. (*note Gperf Declarations::).
  1133.  
  1134. `-e KEYWORD-DELIMITER-LIST'
  1135. `--delimiters=KEYWORD-DELIMITER-LIST'
  1136.      Allows you to provide a string containing delimiters used to
  1137.      separate keywords from their attributes.  The default is ",".  This
  1138.      option is essential if you want to use keywords that have embedded
  1139.      commas or newlines.  One useful trick is to use -e'TAB', where TAB
  1140.      is the literal tab character.
  1141.  
  1142. `-t'
  1143. `--struct-type'
  1144.      Allows you to include a `struct' type declaration for generated
  1145.      code.  Any text before a pair of consecutive `%%' is considered
  1146.      part of the type declaration.  Keywords and additional fields may
  1147.      follow this, one group of fields per line.  A set of examples for
  1148.      generating perfect hash tables and functions for Ada, C, C++,
  1149.      Pascal, Modula 2, Modula 3 and JavaScript reserved words are
  1150.      distributed with this release.
  1151.  
  1152. `--ignore-case'
  1153.      Consider upper and lower case ASCII characters as equivalent.  The
  1154.      string comparison will use a case insignificant character
  1155.      comparison.  Note that locale dependent case mappings are ignored.
  1156.      This option is therefore not suitable if a properly
  1157.      internationalized or locale aware case mapping should be used.
  1158.      (For example, in a Turkish locale, the upper case equivalent of
  1159.      the lowercase ASCII letter `i' is the non-ASCII character `capital
  1160.      i with dot above'.)  For this case, it is better to apply an
  1161.      uppercase or lowercase conversion on the string before passing it
  1162.      to the `gperf' generated function.
  1163.  
  1164. 
  1165. File: gperf,  Node: Output Language,  Next: Output Details,  Prev: Input Details,  Up: Options
  1166.  
  1167. 4.3 Options to specify the Language for the Output Code
  1168. =======================================================
  1169.  
  1170. These options are also available as declarations in the input file
  1171. (*note Gperf Declarations::).
  1172.  
  1173. `-L GENERATED-LANGUAGE-NAME'
  1174. `--language=GENERATED-LANGUAGE-NAME'
  1175.      Instructs `gperf' to generate code in the language specified by the
  1176.      option's argument.  Languages handled are currently:
  1177.  
  1178.     `KR-C'
  1179.           Old-style K&R C.  This language is understood by old-style C
  1180.           compilers and ANSI C compilers, but ANSI C compilers may flag
  1181.           warnings (or even errors) because of lacking `const'.
  1182.  
  1183.     `C'
  1184.           Common C.  This language is understood by ANSI C compilers,
  1185.           and also by old-style C compilers, provided that you `#define
  1186.           const' to empty for compilers which don't know about this
  1187.           keyword.
  1188.  
  1189.     `ANSI-C'
  1190.           ANSI C.  This language is understood by ANSI C compilers and
  1191.           C++ compilers.
  1192.  
  1193.     `C++'
  1194.           C++.  This language is understood by C++ compilers.
  1195.  
  1196.      The default is C.
  1197.  
  1198. `-a'
  1199.      This option is supported for compatibility with previous releases
  1200.      of `gperf'.  It does not do anything.
  1201.  
  1202. `-g'
  1203.      This option is supported for compatibility with previous releases
  1204.      of `gperf'.  It does not do anything.
  1205.  
  1206. 
  1207. File: gperf,  Node: Output Details,  Next: Algorithmic Details,  Prev: Output Language,  Up: Options
  1208.  
  1209. 4.4 Options for fine tuning Details in the Output Code
  1210. ======================================================
  1211.  
  1212. Most of these options are also available as declarations in the input
  1213. file (*note Gperf Declarations::).
  1214.  
  1215. `-K SLOT-NAME'
  1216. `--slot-name=SLOT-NAME'
  1217.      This option is only useful when option `-t' (or, equivalently, the
  1218.      `%struct-type' declaration) has been given.  By default, the
  1219.      program assumes the structure component identifier for the keyword
  1220.      is `name'.  This option allows an arbitrary choice of identifier
  1221.      for this component, although it still must occur as the first
  1222.      field in your supplied `struct'.
  1223.  
  1224. `-F INITIALIZERS'
  1225. `--initializer-suffix=INITIALIZERS'
  1226.      This option is only useful when option `-t' (or, equivalently, the
  1227.      `%struct-type' declaration) has been given.  It permits to specify
  1228.      initializers for the structure members following SLOT-NAME in
  1229.      empty hash table entries.  The list of initializers should start
  1230.      with a comma.  By default, the emitted code will zero-initialize
  1231.      structure members following SLOT-NAME.
  1232.  
  1233. `-H HASH-FUNCTION-NAME'
  1234. `--hash-function-name=HASH-FUNCTION-NAME'
  1235.      Allows you to specify the name for the generated hash function.
  1236.      Default name is `hash'.  This option permits the use of two hash
  1237.      tables in the same file.
  1238.  
  1239. `-N LOOKUP-FUNCTION-NAME'
  1240. `--lookup-function-name=LOOKUP-FUNCTION-NAME'
  1241.      Allows you to specify the name for the generated lookup function.
  1242.      Default name is `in_word_set'.  This option permits multiple
  1243.      generated hash functions to be used in the same application.
  1244.  
  1245. `-Z CLASS-NAME'
  1246. `--class-name=CLASS-NAME'
  1247.      This option is only useful when option `-L C++' (or, equivalently,
  1248.      the `%language=C++' declaration) has been given.  It allows you to
  1249.      specify the name of generated C++ class.  Default name is
  1250.      `Perfect_Hash'.
  1251.  
  1252. `-7'
  1253. `--seven-bit'
  1254.      This option specifies that all strings that will be passed as
  1255.      arguments to the generated hash function and the generated lookup
  1256.      function will solely consist of 7-bit ASCII characters (bytes in
  1257.      the range 0..127).  (Note that the ANSI C functions `isalnum' and
  1258.      `isgraph' do _not_ guarantee that a byte is in this range.  Only
  1259.      an explicit test like `c >= 'A' && c <= 'Z'' guarantees this.)
  1260.      This was the default in versions of `gperf' earlier than 2.7; now
  1261.      the default is to support 8-bit and multibyte characters.
  1262.  
  1263. `-l'
  1264. `--compare-lengths'
  1265.      Compare keyword lengths before trying a string comparison.  This
  1266.      option is mandatory for binary comparisons (*note Binary
  1267.      Strings::).  It also might cut down on the number of string
  1268.      comparisons made during the lookup, since keywords with different
  1269.      lengths are never compared via `strcmp'.  However, using `-l'
  1270.      might greatly increase the size of the generated C code if the
  1271.      lookup table range is large (which implies that the switch option
  1272.      `-S' or `%switch' is not enabled), since the length table contains
  1273.      as many elements as there are entries in the lookup table.
  1274.  
  1275. `-c'
  1276. `--compare-strncmp'
  1277.      Generates C code that uses the `strncmp' function to perform
  1278.      string comparisons.  The default action is to use `strcmp'.
  1279.  
  1280. `-C'
  1281. `--readonly-tables'
  1282.      Makes the contents of all generated lookup tables constant, i.e.,
  1283.      "readonly".  Many compilers can generate more efficient code for
  1284.      this by putting the tables in readonly memory.
  1285.  
  1286. `-E'
  1287. `--enum'
  1288.      Define constant values using an enum local to the lookup function
  1289.      rather than with #defines.  This also means that different lookup
  1290.      functions can reside in the same file.  Thanks to James Clark
  1291.      `<jjc@ai.mit.edu>'.
  1292.  
  1293. `-I'
  1294. `--includes'
  1295.      Include the necessary system include file, `<string.h>', at the
  1296.      beginning of the code.  By default, this is not done; the user must
  1297.      include this header file himself to allow compilation of the code.
  1298.  
  1299. `-G'
  1300. `--global-table'
  1301.      Generate the static table of keywords as a static global variable,
  1302.      rather than hiding it inside of the lookup function (which is the
  1303.      default behavior).
  1304.  
  1305. `-P'
  1306. `--pic'
  1307.      Optimize the generated table for inclusion in shared libraries.
  1308.      This reduces the startup time of programs using a shared library
  1309.      containing the generated code.  If the option `-t' (or,
  1310.      equivalently, the `%struct-type' declaration) is also given, the
  1311.      first field of the user-defined struct must be of type `int', not
  1312.      `char *', because it will contain offsets into the string pool
  1313.      instead of actual strings.  To convert such an offset to a string,
  1314.      you can use the expression `stringpool + O', where O is the
  1315.      offset.  The string pool name can be changed through the option
  1316.      `--string-pool-name'.
  1317.  
  1318. `-Q STRING-POOL-NAME'
  1319. `--string-pool-name=STRING-POOL-NAME'
  1320.      Allows you to specify the name of the generated string pool
  1321.      created by option `-P'.  The default name is `stringpool'.  This
  1322.      option permits the use of two hash tables in the same file, with
  1323.      `-P' and even when the option `-G' (or, equivalently, the
  1324.      `%global-table' declaration) is given.
  1325.  
  1326. `--null-strings'
  1327.      Use NULL strings instead of empty strings for empty keyword table
  1328.      entries.  This reduces the startup time of programs using a shared
  1329.      library containing the generated code (but not as much as option
  1330.      `-P'), at the expense of one more test-and-branch instruction at
  1331.      run time.
  1332.  
  1333. `-W HASH-TABLE-ARRAY-NAME'
  1334. `--word-array-name=HASH-TABLE-ARRAY-NAME'
  1335.      Allows you to specify the name for the generated array containing
  1336.      the hash table.  Default name is `wordlist'.  This option permits
  1337.      the use of two hash tables in the same file, even when the option
  1338.      `-G' (or, equivalently, the `%global-table' declaration) is given.
  1339.  
  1340. `-S TOTAL-SWITCH-STATEMENTS'
  1341. `--switch=TOTAL-SWITCH-STATEMENTS'
  1342.      Causes the generated C code to use a `switch' statement scheme,
  1343.      rather than an array lookup table.  This can lead to a reduction
  1344.      in both time and space requirements for some input files.  The
  1345.      argument to this option determines how many `switch' statements
  1346.      are generated.  A value of 1 generates 1 `switch' containing all
  1347.      the elements, a value of 2 generates 2 tables with 1/2 the
  1348.      elements in each `switch', etc.  This is useful since many C
  1349.      compilers cannot correctly generate code for large `switch'
  1350.      statements.  This option was inspired in part by Keith Bostic's
  1351.      original C program.
  1352.  
  1353. `-T'
  1354. `--omit-struct-type'
  1355.      Prevents the transfer of the type declaration to the output file.
  1356.      Use this option if the type is already defined elsewhere.
  1357.  
  1358. `-p'
  1359.      This option is supported for compatibility with previous releases
  1360.      of `gperf'.  It does not do anything.
  1361.  
  1362. 
  1363. File: gperf,  Node: Algorithmic Details,  Next: Verbosity,  Prev: Output Details,  Up: Options
  1364.  
  1365. 4.5 Options for changing the Algorithms employed by `gperf'
  1366. ===========================================================
  1367.  
  1368. `-k SELECTED-BYTE-POSITIONS'
  1369. `--key-positions=SELECTED-BYTE-POSITIONS'
  1370.      Allows selection of the byte positions used in the keywords' hash
  1371.      function.  The allowable choices range between 1-255, inclusive.
  1372.      The positions are separated by commas, e.g., `-k 9,4,13,14';
  1373.      ranges may be used, e.g., `-k 2-7'; and positions may occur in any
  1374.      order.  Furthermore, the wildcard '*' causes the generated hash
  1375.      function to consider *all* byte positions in each keyword, whereas
  1376.      '$' instructs the hash function to use the "final byte" of a
  1377.      keyword (this is the only way to use a byte position greater than
  1378.      255, incidentally).
  1379.  
  1380.      For instance, the option `-k 1,2,4,6-10,'$'' generates a hash
  1381.      function that considers positions 1,2,4,6,7,8,9,10, plus the last
  1382.      byte in each keyword (which may be at a different position for each
  1383.      keyword, obviously).  Keywords with length less than the indicated
  1384.      byte positions work properly, since selected byte positions
  1385.      exceeding the keyword length are simply not referenced in the hash
  1386.      function.
  1387.  
  1388.      This option is not normally needed since version 2.8 of `gperf';
  1389.      the default byte positions are computed depending on the keyword
  1390.      set, through a search that minimizes the number of byte positions.
  1391.  
  1392. `-D'
  1393. `--duplicates'
  1394.      Handle keywords whose selected byte sets hash to duplicate values.
  1395.      Duplicate hash values can occur if a set of keywords has the same
  1396.      names, but possesses different attributes, or if the selected byte
  1397.      positions are not well chosen.  With the -D option `gperf' treats
  1398.      all these keywords as part of an equivalence class and generates a
  1399.      perfect hash function with multiple comparisons for duplicate
  1400.      keywords.  It is up to you to completely disambiguate the keywords
  1401.      by modifying the generated C code.  However, `gperf' helps you out
  1402.      by organizing the output.
  1403.  
  1404.      Using this option usually means that the generated hash function
  1405.      is no longer perfect.  On the other hand, it permits `gperf' to
  1406.      work on keyword sets that it otherwise could not handle.
  1407.  
  1408. `-m ITERATIONS'
  1409. `--multiple-iterations=ITERATIONS'
  1410.      Perform multiple choices of the `-i' and `-j' values, and choose
  1411.      the best results.  This increases the running time by a factor of
  1412.      ITERATIONS but does a good job minimizing the generated table size.
  1413.  
  1414. `-i INITIAL-VALUE'
  1415. `--initial-asso=INITIAL-VALUE'
  1416.      Provides an initial VALUE for the associate values array.  Default
  1417.      is 0.  Increasing the initial value helps inflate the final table
  1418.      size, possibly leading to more time efficient keyword lookups.
  1419.      Note that this option is not particularly useful when `-S' (or,
  1420.      equivalently, `%switch') is used.  Also, `-i' is overridden when
  1421.      the `-r' option is used.
  1422.  
  1423. `-j JUMP-VALUE'
  1424. `--jump=JUMP-VALUE'
  1425.      Affects the "jump value", i.e., how far to advance the associated
  1426.      byte value upon collisions.  JUMP-VALUE is rounded up to an odd
  1427.      number, the default is 5.  If the JUMP-VALUE is 0 `gperf' jumps by
  1428.      random amounts.
  1429.  
  1430. `-n'
  1431. `--no-strlen'
  1432.      Instructs the generator not to include the length of a keyword when
  1433.      computing its hash value.  This may save a few assembly
  1434.      instructions in the generated lookup table.
  1435.  
  1436. `-r'
  1437. `--random'
  1438.      Utilizes randomness to initialize the associated values table.
  1439.      This frequently generates solutions faster than using deterministic
  1440.      initialization (which starts all associated values at 0).
  1441.      Furthermore, using the randomization option generally increases
  1442.      the size of the table.
  1443.  
  1444. `-s SIZE-MULTIPLE'
  1445. `--size-multiple=SIZE-MULTIPLE'
  1446.      Affects the size of the generated hash table.  The numeric
  1447.      argument for this option indicates "how many times larger or
  1448.      smaller" the maximum associated value range should be, in
  1449.      relationship to the number of keywords.  It can be written as an
  1450.      integer, a floating-point number or a fraction.  For example, a
  1451.      value of 3 means "allow the maximum associated value to be about 3
  1452.      times larger than the number of input keywords".  Conversely, a
  1453.      value of 1/3 means "allow the maximum associated value to be about
  1454.      3 times smaller than the number of input keywords".  Values
  1455.      smaller than 1 are useful for limiting the overall size of the
  1456.      generated hash table, though the option `-m' is better at this
  1457.      purpose.
  1458.  
  1459.      If `generate switch' option `-S' (or, equivalently, `%switch') is
  1460.      _not_ enabled, the maximum associated value influences the static
  1461.      array table size, and a larger table should decrease the time
  1462.      required for an unsuccessful search, at the expense of extra table
  1463.      space.
  1464.  
  1465.      The default value is 1, thus the default maximum associated value
  1466.      about the same size as the number of keywords (for efficiency, the
  1467.      maximum associated value is always rounded up to a power of 2).
  1468.      The actual table size may vary somewhat, since this technique is
  1469.      essentially a heuristic.
  1470.  
  1471. 
  1472. File: gperf,  Node: Verbosity,  Prev: Algorithmic Details,  Up: Options
  1473.  
  1474. 4.6 Informative Output
  1475. ======================
  1476.  
  1477. `-h'
  1478. `--help'
  1479.      Prints a short summary on the meaning of each program option.
  1480.      Aborts further program execution.
  1481.  
  1482. `-v'
  1483. `--version'
  1484.      Prints out the current version number.
  1485.  
  1486. `-d'
  1487. `--debug'
  1488.      Enables the debugging option.  This produces verbose diagnostics to
  1489.      "standard error" when `gperf' is executing.  It is useful both for
  1490.      maintaining the program and for determining whether a given set of
  1491.      options is actually speeding up the search for a solution.  Some
  1492.      useful information is dumped at the end of the program when the
  1493.      `-d' option is enabled.
  1494.  
  1495. 
  1496. File: gperf,  Node: Bugs,  Next: Projects,  Prev: Options,  Up: Top
  1497.  
  1498. 5 Known Bugs and Limitations with `gperf'
  1499. *****************************************
  1500.  
  1501. The following are some limitations with the current release of `gperf':
  1502.  
  1503.    * The `gperf' utility is tuned to execute quickly, and works quickly
  1504.      for small to medium size data sets (around 1000 keywords).  It is
  1505.      extremely useful for maintaining perfect hash functions for
  1506.      compiler keyword sets.  Several recent enhancements now enable
  1507.      `gperf' to work efficiently on much larger keyword sets (over
  1508.      15,000 keywords).  When processing large keyword sets it helps
  1509.      greatly to have over 8 megs of RAM.
  1510.  
  1511.    * The size of the generate static keyword array can get _extremely_
  1512.      large if the input keyword file is large or if the keywords are
  1513.      quite similar.  This tends to slow down the compilation of the
  1514.      generated C code, and _greatly_ inflates the object code size.  If
  1515.      this situation occurs, consider using the `-S' option to reduce
  1516.      data size, potentially increasing keyword recognition time a
  1517.      negligible amount.  Since many C compilers cannot correctly
  1518.      generate code for large switch statements it is important to
  1519.      qualify the -S option with an appropriate numerical argument that
  1520.      controls the number of switch statements generated.
  1521.  
  1522.    * The maximum number of selected byte positions has an arbitrary
  1523.      limit of 255.  This restriction should be removed, and if anyone
  1524.      considers this a problem write me and let me know so I can remove
  1525.      the constraint.
  1526.  
  1527. 
  1528. File: gperf,  Node: Projects,  Next: Bibliography,  Prev: Bugs,  Up: Top
  1529.  
  1530. 6 Things Still Left to Do
  1531. *************************
  1532.  
  1533. It should be "relatively" easy to replace the current perfect hash
  1534. function algorithm with a more exhaustive approach; the perfect hash
  1535. module is essential independent from other program modules.  Additional
  1536. worthwhile improvements include:
  1537.  
  1538.    * Another useful extension involves modifying the program to generate
  1539.      "minimal" perfect hash functions (under certain circumstances, the
  1540.      current version can be rather extravagant in the generated table
  1541.      size).  This is mostly of theoretical interest, since a sparse
  1542.      table often produces faster lookups, and use of the `-S' `switch'
  1543.      option can minimize the data size, at the expense of slightly
  1544.      longer lookups (note that the gcc compiler generally produces good
  1545.      code for `switch' statements, reducing the need for more complex
  1546.      schemes).
  1547.  
  1548.    * In addition to improving the algorithm, it would also be useful to
  1549.      generate an Ada package as the code output, in addition to the
  1550.      current C and C++ routines.
  1551.  
  1552. 
  1553. File: gperf,  Node: Bibliography,  Next: Concept Index,  Prev: Projects,  Up: Top
  1554.  
  1555. 7 Bibliography
  1556. **************
  1557.  
  1558. [1] Chang, C.C.: A Scheme for Constructing Ordered Minimal Perfect
  1559. Hashing Functions Information Sciences 39(1986), 187-195.
  1560.  
  1561.    [2] Cichelli, Richard J. Author's Response to "On Cichelli's Minimal
  1562. Perfect Hash Functions Method" Communications of the ACM, 23,
  1563. 12(December 1980), 729.
  1564.  
  1565.    [3] Cichelli, Richard J. Minimal Perfect Hash Functions Made Simple
  1566. Communications of the ACM, 23, 1(January 1980), 17-19.
  1567.  
  1568.    [4] Cook, C. R. and Oldehoeft, R.R. A Letter Oriented Minimal
  1569. Perfect Hashing Function SIGPLAN Notices, 17, 9(September 1982), 18-27.
  1570.  
  1571.    [5] Cormack, G. V. and Horspool, R. N. S. and Kaiserwerth, M.
  1572. Practical Perfect Hashing Computer Journal, 28, 1(January 1985), 54-58.
  1573.  
  1574.    [6] Jaeschke, G. Reciprocal Hashing: A Method for Generating Minimal
  1575. Perfect Hashing Functions Communications of the ACM, 24, 12(December
  1576. 1981), 829-833.
  1577.  
  1578.    [7] Jaeschke, G. and Osterburg, G. On Cichelli's Minimal Perfect
  1579. Hash Functions Method Communications of the ACM, 23, 12(December 1980),
  1580. 728-729.
  1581.  
  1582.    [8] Sager, Thomas J. A Polynomial Time Generator for Minimal Perfect
  1583. Hash Functions Communications of the ACM, 28, 5(December 1985), 523-532
  1584.  
  1585.    [9] Schmidt, Douglas C. GPERF: A Perfect Hash Function Generator
  1586. Second USENIX C++ Conference Proceedings, April 1990.
  1587.  
  1588.    [10] Schmidt, Douglas C. GPERF: A Perfect Hash Function Generator
  1589. C++ Report, SIGS 10 10 (November/December 1998).
  1590.  
  1591.    [11] Sebesta, R.W. and Taylor, M.A. Minimal Perfect Hash Functions
  1592. for Reserved Word Lists  SIGPLAN Notices, 20, 12(September 1985), 47-53.
  1593.  
  1594.    [12] Sprugnoli, R. Perfect Hashing Functions: A Single Probe
  1595. Retrieving Method for Static Sets Communications of the ACM, 20
  1596. 11(November 1977), 841-850.
  1597.  
  1598.    [13] Stallman, Richard M. Using and Porting GNU CC Free Software
  1599. Foundation, 1988.
  1600.  
  1601.    [14] Stroustrup, Bjarne The C++ Programming Language.
  1602. Addison-Wesley, 1986.
  1603.  
  1604.    [15] Tiemann, Michael D. User's Guide to GNU C++ Free Software
  1605. Foundation, 1989.
  1606.  
  1607. 
  1608. File: gperf,  Node: Concept Index,  Prev: Bibliography,  Up: Top
  1609.  
  1610. Concept Index
  1611. *************
  1612.  
  1613. [index]
  1614. * Menu:
  1615.  
  1616. * %%:                                    User-supplied Struct.
  1617.                                                               (line  33)
  1618. * %7bit:                                 Gperf Declarations.  (line  95)
  1619. * %compare-lengths:                      Gperf Declarations.  (line 103)
  1620. * %compare-strncmp:                      Gperf Declarations.  (line 115)
  1621. * %define class-name:                    Gperf Declarations.  (line  89)
  1622. * %define hash-function-name:            Gperf Declarations.  (line  79)
  1623. * %define initializer-suffix:            Gperf Declarations.  (line  71)
  1624. * %define lookup-function-name:          Gperf Declarations.  (line  84)
  1625. * %define slot-name:                     Gperf Declarations.  (line  63)
  1626. * %define string-pool-name:              Gperf Declarations.  (line 152)
  1627. * %define word-array-name:               Gperf Declarations.  (line 167)
  1628. * %delimiters:                           Gperf Declarations.  (line  24)
  1629. * %enum:                                 Gperf Declarations.  (line 124)
  1630. * %global-table:                         Gperf Declarations.  (line 135)
  1631. * %ignore-case:                          Gperf Declarations.  (line  34)
  1632. * %includes:                             Gperf Declarations.  (line 130)
  1633. * %language:                             Gperf Declarations.  (line  39)
  1634. * %null-strings:                         Gperf Declarations.  (line 160)
  1635. * %omit-struct-type:                     Gperf Declarations.  (line 185)
  1636. * %pic:                                  Gperf Declarations.  (line 140)
  1637. * %readonly-tables:                      Gperf Declarations.  (line 119)
  1638. * %struct-type:                          Gperf Declarations.  (line  30)
  1639. * %switch:                               Gperf Declarations.  (line 173)
  1640. * %{:                                    C Code Inclusion.    (line   6)
  1641. * %}:                                    C Code Inclusion.    (line   6)
  1642. * Array name:                            Output Details.      (line 129)
  1643. * Bugs:                                  Contributors.        (line   6)
  1644. * Class name:                            Output Details.      (line  41)
  1645. * Declaration section:                   Input Format.        (line   6)
  1646. * Delimiters:                            Input Details.       (line  11)
  1647. * Duplicates:                            Algorithmic Details. (line  32)
  1648. * Format:                                Input Format.        (line   6)
  1649. * Functions section:                     Input Format.        (line   6)
  1650. * hash:                                  Output Format.       (line  14)
  1651. * hash table:                            Output Format.       (line   6)
  1652. * in_word_set:                           Output Format.       (line  24)
  1653. * Initializers:                          Output Details.      (line  20)
  1654. * Jump value:                            Algorithmic Details. (line  63)
  1655. * Keywords section:                      Input Format.        (line   6)
  1656. * Minimal perfect hash functions:        Search Structures.   (line  30)
  1657. * NUL:                                   Binary Strings.      (line   6)
  1658. * Slot name:                             Output Details.      (line  11)
  1659. * Static search structure:               Search Structures.   (line   6)
  1660. * switch <1>:                            Output Details.      (line 136)
  1661. * switch:                                Output Format.       (line  44)
  1662.  
  1663.  
  1664. 
  1665. Tag Table:
  1666. Node: Top1282
  1667. Node: Copying3358
  1668. Node: Contributors22510
  1669. Node: Motivation23698
  1670. Node: Search Structures24822
  1671. Node: Description28373
  1672. Node: Input Format30265
  1673. Node: Declarations31402
  1674. Node: User-supplied Struct31982
  1675. Node: Gperf Declarations33589
  1676. Node: C Code Inclusion42007
  1677. Node: Keywords42842
  1678. Node: Functions44782
  1679. Node: Controls for GNU indent45312
  1680. Node: Output Format46255
  1681. Node: Binary Strings49041
  1682. Node: Options50184
  1683. Node: Output File50965
  1684. Node: Input Details51352
  1685. Node: Output Language53183
  1686. Node: Output Details54594
  1687. Node: Algorithmic Details61509
  1688. Node: Verbosity66761
  1689. Node: Bugs67467
  1690. Node: Projects69055
  1691. Node: Bibliography70179
  1692. Node: Concept Index72231
  1693. 
  1694. End Tag Table
  1695.